Conventional Commits 1.0.0 (日本語訳)
コミットメッセージに人間や機械が読める意味を付加するための仕様
概要
The Conventional Commits specification は、コミットメッセージを利用した軽量な規約です。この仕様は、明示的なコミット履歴を作成するための簡単なルールを提供し、その上に自動化されたツールを簡単に書くことができます。この規約は、コミットメッセージで行われた機能、修正、および変更点を記述することで、SemVer に対応しています。 コミットメッセージは以下のような構造になっています。
code: SPEC
コミットには、ライブラリの利用者に意図を伝えるために、以下の構造要素が含まれています。
fix： fix タイプのコミットは、コードベースのバグを修正します（セマンティックバージョニングの PATCHと関連しています）。 feat： feat タイプのコミットは、コードベースに新しい機能を導入します（これはセマンティックバージョニングの MINOR と関連しています）。 BREAKING CHANGE： フッターにBREAKING CHANGE:と記載されているか、type/scopeの後に!が付加されているコミットは、ブレークするAPIの変更を導入します（セマンティックバージョニングではMAJOR に相関します）。BREAKING CHANGEは、どのタイプのコミットにも含まれます。 BREAKING CHANGE 以外のフッター： BREAKING CHANGE: <description> 以外のフッターを指定することもでき、git trailer のフォーマットに似た慣習に従います。 追加のタイプは、Conventional Commits の仕様では必須ではなく、セマンティックバージョニングでは暗黙の効果はありません (BREAKING CHANGE を含まない限り)。スコープはコミットの型に追加の文脈情報を提供するために与えられることがあり、括弧内に含まれます。例えば、feat( parser): add ability to parse arrays.
コミットメッセージの例
説明と変更点のフッターを含むコミットメッセージ
code: TEXT
feat: allow provided config object to extend other configs
BREAKING CHANGE: extends key in config file is now used for extending other config files
メッセージに「！」をつけてコミットすることで、速報性のある変化に注意を促す
code: TEXT
feat!: send an email to the customer when a product is shipped
BREAKING CHANGEに注目を集めるために、範囲と「！」でメッセージをコミットする。
code: TEXT
feat(api)!: send an email to the customer when a product is shipped
「！」と"BREAKING CHANGE " の両方のフッターを持つコミットメッセージ
code: TEXT
chore!: drop support for Node 6
BREAKING CHANGE: use JavaScript features not available in Node 6.
ボディのないコミットメッセージ
code: TEXT
docs: correct spelling of CHANGELOG
スコープ付きコミットメッセージ
code: TEXT
feat(lang): add polish language
複数段落の本文と複数のフッターを持つコミットメッセージ
code: TEXT
fix: prevent racing of requests
Introduce a request id and a reference to latest request. Dismiss
incoming responses other than from latest request.
Remove timeouts which were used to mitigate the racing issue but are
obsolete now.
Reviewed-by: Z
仕様
本文書のキーワード「MUST」、「MUST NOT」、「REQUIRED」、「SHALL」、「SHALL NOT」、「SHOULD」、「SHOULD NOT」、「RECOMMENDED」、「MAY」、「OPTIONAL」は、RFC2119 に記載されている通りに解釈されます。 １．コミットの前にはタイプを付けなければなりません（MUST）。タイプは名詞、feat、fixなどからなり、その後にはOPTIONALのスコープ、OPTIONALの！、REQUIREDのコロン(:)とスペース( )が続きます。
２．タイプfeatは、コミットによってアプリケーションやライブラリに新しい機能が追加される場合に使用しなければなりません（MUST）。
３．タイプfixは、アプリケーションのバグフィックスを示すコミットの場合に使用しなければなりません（MUST）。
４．タイプの後にスコープを指定してもかまいません（MAY）。スコープは、コードベースのセクションを説明する名詞を括弧で囲んで構成しなければなりません（MUST）。たとえば、fix(perser) などです。
５．type/scopeの接頭辞の後のコロンとスペースのすぐ後に、説明文を記述しなければなりません（MUST）。説明文はコードの変更点を短くまとめたものです。例: fix: array parsing issue when multiple spaces were contained in string.
６．短い説明の後には、コードの変更点に関する文脈上の追加情報として、より長いコミットボディを提供してもかまいません（MAY）。本文は、説明文の1行後に空行で始めなければなりません（MUST）。
７．コミットボディは自由形式で、改行で区切られた任意の数のパラグラフで構成してもよいものとします。
８．本文の1行後には、1つ以上のフッターを記述してもかまいません(MAY)。各フッターは、単語のトークンと、
それに続く :<space> または <space># のセパレーター、そして文字列の値で構成されなければなりません (これは git trailer の規約にヒントを得ています)。 ９．フッターのトークンは、Acked-byなどようにホワイトスペース文字の代わりに-を使用しなければなりません（これは、フッターセクションを複数段落の本文から区別するのに役立ちます）。ただし、BREAKING CHANGE は例外で、これもトークンとして使用してもよい。
１０．フッターの値にはスペースや改行を含めてもよく、次の有効なフッターのトークンとセパレータのペアが観測された時点で解析を終了しなければならない（MUST）。
１１．ブレーキングチェンジは、コミットのtype/scopeプレフィックスか、フッターのエントリで示されなければなりません(MUST)。
１２．フッターに含まれる場合、変更点は大文字のBREAKING CHANGEの後に、コロン、スペース、説明文で構成されなければなりません。例：BREAKING CHANGE: environment variables now take precedence over config files
１３．type/scopeプレフィックスに含まれる場合、BREAKING CHANGEは、:の直前に! ! を使用した場合、
BREAKING CHANGE: はフッターセクションから省略してもかまいません(MAY)。また、コミットの説明文を使用して breaking change を説明しなければなりません。
１４．コミットメッセージには feat や fix 以外のタイプを使用してもかまいません。例：docs: updated ref docs
従来のコミットを構成する情報単位は、実装者が大文字小文字を区別してはいけません(MUST NOT)。ただし、BREAKING １１１５．CHANGE は例外で、大文字でなければなりません(MUST)。
１６．BREAKING-CHANGE は、フッターのトークンとして使用される場合、BREAKING CHANGE と同義でなければならない(MUST)。
Conventional Commits を使う理由
CHANGELOGを自動的に生成する。
着地(bump)したコミットの種類に基づいて、セマンティックなバージョンバンプを自動的に決定します。
チームメイトやパブリック、その他のステークホルダーに変更内容を伝える。
ビルドやパブリッシュのプロセスを起動する
より構造化されたコミット履歴を探索できるようにすることで、プロジェクトへの貢献を容易にします。
よくある質問(FAQ)
開発初期段階でのコミットメッセージにはどのように対処すればよいのでしょうか？
すでに製品をリリースしているかのように進めることをお勧めします。通常、誰かが、たとえそれが仲間のソフトウェア開発者であっても、あなたのソフトウェアを使用しています。彼らは、何が修正されたのか、何が壊れたのかなどを知りたがるでしょう。
コミットタイトルのタイプは大文字ですか、小文字ですか？
どのような表記でも構いませんが、一貫性を持たせた方が良いでしょう。
コミットが複数のコミットタイプに当てはまる場合はどうすればいいですか？
可能な限りさかのぼって複数のコミットを行ってください。Conventional Commitsの利点の一つは、私たちがより整理されたコミットやPRを作るように仕向けることができることです。
これでは、迅速な開発や早い反復ができなくなるのではないですか？
整理されていない方法で速く動くことを阻止します。これは、様々なコントリビューターが参加する複数のプロジェクトにおいて、長期的に高速な開発を行うことを可能にします。
Conventional Commits は、開発者が提供されたタイプの中で考えることになるので、コミットのタイプを制限することになるのでは？
Conventional Commits は、修正などの特定のタイプのコミットをより多く行うように促します。それ以外にも、Conventional Commitsの柔軟性により、チームが独自のタイプを考え、時間の経過とともにそのタイプを変更することができます。
これはSemVerとどのように関連していますか？
fixタイプのコミットは、PATCHリリースに変換されます。featタイプのコミットは、MINORリリースに変換されます。BREAKING CHANGEが含まれるコミットは、タイプに関わらずMAJORリリースに翻訳されるべきです。
Conventional Commits Specification (例: @jameswomack/conventional-commit-spec) の拡張機能は、どのようにバージョン管理すればよいですか?
SemVerを使用して、この仕様に対する独自の拡張機能をリリースすることをお勧めします(また、これらの拡張機能を作成することをお勧めします)。
間違ったコミットタイプを使用してしまった場合はどうすればいいですか？
featではなくfixのように、仕様に沿ったタイプであっても、正しいタイプではないものを使用した場合
間違ったコミットをマージしたりリリースしたりする前に、git rebase -i を使ってコミット履歴を編集することをおすすめします。リリース後の後始末は、どのようなツールやプロセスを使うかによって異なります。
仕様にないタイプを使ってしまった場合 (例: feat ではなく feet)
最悪の場合、Conventional Commitsの仕様に合わないコミットが発生したとしても、世界の終わりではありません。単に、そのコミットが仕様に基づいたツールに見落とされてしまうということです。
すべてのコントリビューターがConventional Commitsの仕様を使う必要がありますか？
そうではありません。Git のリードメンテナがスクウォッシュベースのワークフローを使っていれば、コミットメッセージがマージされるたびにメンテナがクリーンアップすることができ、カジュアルなコミッターには負担がかかりません。一般的なワークフローとしては、Git システムがプルリクエストからのコミットを自動的にスカッシュし、リードメンテナがマージ時に適切な git コミットメッセージを入力するためのフォームを表示するというものがあります。
リバートコミットはどのように扱うのですか？
複数のコミットを元に戻すのか、機能を元に戻す場合、次のリリースはパッチにすべきなのかなど、コードの元に戻す作業は複雑です。
Conventional Commits では、リバートの動作を明示的に定義していません。その代わりに、型やフッターの柔軟性を利用して、ツールの作者がリバートを処理するロジックを開発することにしています。
推奨される方法としては、revert タイプを使用し、フッターには戻されるコミットの SHA を参照するようにします。
code: TEXT
revert: let us never again speak of the noodle incident
Refs: 676104e, a215868